<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>AngelScript: Registering a reference type</title>

<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>


</head>
<body>
<div id="top"><!-- do not remove this div! -->


<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  
  
  <td style="padding-left: 0.5em;">
   <div id="projectname">AngelScript
   
   </div>
   
  </td>
  
  
  
   
  
 </tr>
 </tbody>
</table>
</div>

<!-- Generated by Doxygen 1.7.5.1 -->
</div>
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
  initNavTree('doc_reg_basicref.html','');
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">Registering a reference type </div>  </div>
</div>
<div class="contents">
<div class="textblock"><p>The basic reference type should be registered with the following behaviours: <a class="el" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a0b3db16eea35213b6f41f8d19dc1bd4c">asBEHAVE_FACTORY</a>, <a class="el" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a1dfa5b72ad69a7bf70636d4fcb1b1d84">asBEHAVE_ADDREF</a>, and <a class="el" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a7134ce13c81967191af401a1e5170a0c">asBEHAVE_RELEASE</a>.</p>
<div class="fragment"><pre class="fragment"><span class="comment">// Registering the reference type</span>
r = engine-&gt;<a class="code" href="classas_i_script_engine.html#a29c6c087c8c5b5cdb6271cfd161cc5a6" title="Registers a new object type.">RegisterObjectType</a>(<span class="stringliteral">&quot;ref&quot;</span>, 0, <a class="code" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa9450e038342b36c745858d2e5ae4b861" title="A reference type.">asOBJ_REF</a>); assert( r &gt;= 0 );
</pre></div><dl class="see"><dt><b>See also:</b></dt><dd>The <a class="el" href="doc_addon_any.html">any</a> add-on for an example of a reference type.</dd>
<dd>
<a class="el" href="doc_gc_object.html">Garbage collected objects</a>, <a class="el" href="doc_adv_class_hierarchy.html">Class hierarchies</a>, <a class="el" href="doc_adv_scoped_type.html">Registering a scoped reference type</a>, and <a class="el" href="doc_adv_single_ref_type.html">Registering a single-reference type</a> for more advanced types.</dd></dl>
<h2><a class="anchor" id="doc_reg_basicref_1"></a>
Factory function</h2>
<p>The factory function is the one that AngelScript will use to instanciate objects of this type when a variable is declared. It is responsible for allocating and initializing the object memory.</p>
<p>The default factory function doesn't take any parameters and should return an object handle for the new object. Make sure the object's reference counter is accounting for the reference being returned by the factory function, so that the object is properly released when all references to it are removed.</p>
<div class="fragment"><pre class="fragment">CRef::CRef()
{
    <span class="comment">// Let the constructor initialize the reference counter to 1</span>
    refCount = 1;
}

CRef *Ref_Factory()
{
    <span class="comment">// The class constructor is initializing the reference counter to 1</span>
    <span class="keywordflow">return</span> <span class="keyword">new</span> CRef();
}

<span class="comment">// Registering the factory behaviour</span>
r = engine-&gt;<a class="code" href="classas_i_script_engine.html#a7ea3c93dea338b0287027de0e4895dcb" title="Registers a behaviour for the object type.">RegisterObjectBehaviour</a>(<span class="stringliteral">&quot;ref&quot;</span>, <a class="code" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a0b3db16eea35213b6f41f8d19dc1bd4c" title="Factory.">asBEHAVE_FACTORY</a>, <span class="stringliteral">&quot;ref@ f()&quot;</span>, <a class="code" href="angelscript_8h.html#a78f8f2c7f1c88b12e74a5ac47b4184ae" title="Returns an asSFuncPtr representing the function specified by the name.">asFUNCTION</a>(Ref_Factory), <a class="code" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4a68ae43cc91cdfc3fa4590c9e6164e4f4" title="A cdecl function.">asCALL_CDECL</a>); assert( r &gt;= 0 );
</pre></div><p>You may also register factory functions that take parameters, which may then be used when initializing the object.</p>
<p>The factory function must be registered as a global function, but can be implemented as a static class method, common global function, or a global function following the generic calling convention.</p>
<h2><a class="anchor" id="doc_reg_basicref_2"></a>
Addref and release behaviours</h2>
<div class="fragment"><pre class="fragment"><span class="keywordtype">void</span> CRef::Addref()
{
    <span class="comment">// Increase the reference counter</span>
    refCount++;
}

<span class="keywordtype">void</span> CRef::Release()
{
    <span class="comment">// Decrease ref count and delete if it reaches 0</span>
    <span class="keywordflow">if</span>( --refCount == 0 )
        <span class="keyword">delete</span> <span class="keyword">this</span>;
}

<span class="comment">// Registering the addref/release behaviours</span>
r = engine-&gt;<a class="code" href="classas_i_script_engine.html#a7ea3c93dea338b0287027de0e4895dcb" title="Registers a behaviour for the object type.">RegisterObjectBehaviour</a>(<span class="stringliteral">&quot;ref&quot;</span>, <a class="code" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a1dfa5b72ad69a7bf70636d4fcb1b1d84" title="AddRef.">asBEHAVE_ADDREF</a>, <span class="stringliteral">&quot;void f()&quot;</span>, <a class="code" href="angelscript_8h.html#a7345e6b3afabec24efd0ff77886d49a6" title="Returns an asSFuncPtr representing the class method specified by class and method name...">asMETHOD</a>(CRef,AddRef), <a class="code" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4aea516c8742acc1edff6a43dc1bb09e96" title="A thiscall class method.">asCALL_THISCALL</a>); assert( r &gt;= 0 );
r = engine-&gt;<a class="code" href="classas_i_script_engine.html#a7ea3c93dea338b0287027de0e4895dcb" title="Registers a behaviour for the object type.">RegisterObjectBehaviour</a>(<span class="stringliteral">&quot;ref&quot;</span>, <a class="code" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a7134ce13c81967191af401a1e5170a0c" title="Release.">asBEHAVE_RELEASE</a>, <span class="stringliteral">&quot;void f()&quot;</span>, <a class="code" href="angelscript_8h.html#a7345e6b3afabec24efd0ff77886d49a6" title="Returns an asSFuncPtr representing the class method specified by class and method name...">asMETHOD</a>(CRef,Release), <a class="code" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4aea516c8742acc1edff6a43dc1bb09e96" title="A thiscall class method.">asCALL_THISCALL</a>); assert( r &gt;= 0 );
</pre></div><h2><a class="anchor" id="doc_reg_noinst"></a>
Registering an uninstanciable reference type</h2>
<p>Sometimes it may be useful to register types that cannot be instanciated by the scripts, yet can be interacted with. You can do this by registering the type as a normal reference type, but omit the registration of the factory behaviour. You can later register global properties, or functions that allow the scripts to access objects created by the application via object handles.</p>
<p>This would be used when the application has a limited number of objects available and doesn't want to create new ones. For example singletons, or pooled objects. </p>
</div></div>
</div>
  <div id="nav-path" class="navpath">
    <ul>

    <li class="footer">Generated on Sun Jan 29 2012 15:41:04 for AngelScript by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.5.1 </li>
   </ul>
 </div>


</body>
</html>
